Skip to content

[MRG] Honor the documented unbalanced=float("inf") contract without changing the objective - #895

Open
xihaian251 wants to merge 3 commits into
PythonOT:masterfrom
xihaian251:fix/solve-inf-marginal-contract
Open

xihaian251 wants to merge 3 commits into
PythonOT:masterfrom
xihaian251:fix/solve-inf-marginal-contract

Conversation

@xihaian251

@xihaian251 xihaian251 commented Oct 21, 2026 •

Copy link
Copy Markdown
Contributor

Types of changes

  • Bug fix

Motivation and context

ot.solve documents unbalanced=float("inf") as the balanced OT limit. On unmodified master the exact (MM) and L-BFGSB paths do not honor this sentinel:

  • reg=0, unbalanced=inf returns value=NaN and an all-NaN plan;
  • reg>0, reg_type="L2"|"entropy", unbalanced=inf returns value=NaN while silently returning a balanced plan [[0.25,0.25],[0.25,0.25]];
  • one-sided (+inf, rho) returns NaN or silently solves the balanced problem.

The root cause is objective mismatch: the hard marginal-constraint limit of ⟨M,T⟩+λR(T;c)+ρ_aD(T1,a)+ρ_bD(Tᵀ1,b) keeps the original ⟨M,T⟩+λR(T;c), which is only equal to what the balanced branch minimizes for a subset of combinations. Dispatching all inf cases to the balanced solver solves a different problem.

Mathematical contract (independent Wolfram oracles)

  • L2 reference measure (M=[[0,1],[1,0]], a=b=[0.5,0.5], c=abᵀ): hard limit ⟨M,T⟩+(reg/2)‖T−c‖² gives V*=0.125 (reg=1) / 0.25 (reg=2), while balanced ⟨M,T⟩+(reg/2)‖T‖² gives 0.25 / 0.50. With non-uniform a=[0.7,0.3], b=[0.6,0.4], the optimal plans differ: T00=0.42 vs 0.40. This holds even after PR [MRG] Report the half-squared L2 objective that smooth_ot_dual minimises #914 corrected the balanced value coefficient.
  • KL with custom c: ⟨M,T⟩+KL(T‖c), c=[[0.45,0.05],[0.05,0.45]] gives T00*=9e/(2+18e)=0.4803648497, V*=0.0652983360. The entropic KL Sinkhorn path implements this correctly and is left untouched.
  • entropy: ΣT(log T−1) and ΣT log T differ by reg at unit mass; plans coincide but reported values do not.
  • one-sided inf, nonzero-cost counterexample: a=[0.6,0.4], b=[0.5,0.5], M=[[0,2],[0,2]], rho=4, first-column mass z. Wolfram gives F(z)=3-6z+4z^2, z*=0.75, F*=0.75, versus balanced z=0.5, F=1.0 — a strict gap of 0.25. A feasible nonnegative plan is T=[[0.4,0.2],[0.35,0.05]] (row sums 0.6/0.4, column sums 0.75/0.25). This proves the semi-relaxed optimum is genuinely different from the balanced plan, not merely non-unique.

Combinations whose limit is not the balanced objective raise an explicit NotImplementedError rather than silently solving another problem.

Implementation

  • Detect +inf (scalar, tuple, list, array) before dispatch; tracers and non-positive-inf values keep prior behavior.
  • Route to the balanced solver only where mathematically equivalent: reg=0 (regularizer vanishes), reg_type="KL" with default c=abᵀ, and user-supplied (f, df) pairs.
  • Leave the already-correct entropic KL Sinkhorn path unchanged (including custom c, potentials_init, method).
  • Reject one-sided infinite relaxations except on the entropic KL path, and reject all infinite relaxations on the exact MM / L-BFGSB paths.
  • Add docstring notes in mm_unbalanced, lbfgsb_unbalanced that ot.solve resolves the sentinel before calling them.

The MM / L-BFGSB / Sinkhorn cores are not rewritten. This PR does not change the existing balanced L2 implementation. PR #914 separately fixes that objective's half-squared coefficient and is not yet merged into master; therefore on a tree containing only this PR, reg=1, reg_type="L2", unbalanced=None still reports the pre-#914 value 0.5. This is expected and is not a regression of this PR — it must not be fixed here by mixing in #914 code. In the validated combined integration tree (#914 + #895), the corrected value 0.25 is preserved and the infinity dispatch contract still holds.

How has this been tested

  • Real API negative controls on unmodified master reproduce NaN / silent balanced-plan defects in 5 scenarios; all 8 scenarios recorded with plan, value, marginal residuals, convergence and oracle errors.
  • pytest -q test/unbalanced/test_inf_marginal.py: 97 passed / 2 skipped.
  • Integration with PR [MRG] Report the half-squared L2 objective that smooth_ot_dual minimises #914 and [MRG] Fix JAX gradients for dense emd2 #917: 114 passed / 2 skipped for combined inf_marginal + L2 + JAX tests.
  • pytest -q test/unbalanced/: 681 passed / 33 skipped.
  • pytest -q test/test_solvers.py test/test_ot.py test/test_backend.py (integration tree): 1046 passed / 105 skipped.
  • Full executable suite from Phase IV local validation (excluding test/test_bspot.py and test/test_helpers.py due to two pre-existing local environment limits: BSP native-extension ABI mismatch and sandbox-blocked MSVC probe): 3701 passed / 470 skipped / 6 xfailed. After the latest upstream sync ([MRG] Clarify transported mass in partial OT #902) the functional code is byte-for-byte unchanged (only RELEASES.md, docs/source/user_guide.rst and one example file changed), so targeted re-runs were performed instead: test_inf_marginal.py 97 passed / 2 skipped, test/unbalanced/ 681 passed / 33 skipped.
  • TensorFlow is not installed locally, so no TF-backend test was run here. Upstream CI has not yet been confirmed for this head; no CI result is claimed as passing until observed.
  • Ruff 0.5.2 check, NPY201 preview, ruff-format on ot/, and git diff --check all pass.
  • Test comments were updated to use PR [MRG] Report the half-squared L2 objective that smooth_ot_dual minimises #914's corrected balanced-L2 values (0.25 / 0.50) instead of the pre-fix 0.5 / 1.0.

Scope and limitations

This PR changes only ot.solve dispatch and documentation; it does not add semi-relaxed exact OT or extend L-BFGSB to infinite penalties. Combinations raising NotImplementedError require either a finite relaxation or an explicit balanced call with the understanding that it solves a different objective. When upstream master changes further, the merge should be re-validated against the Wolfram oracles and the four-tree compatibility matrix in the audit reports.

@codecov

codecov Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.49123% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 97.08%. Comparing base (700fc19) to head (725243e).

Additional details and impacted files
@@            Coverage Diff             @@
##           master     #895      +/-   ##
==========================================
- Coverage   97.09%   97.08%   -0.01%     
==========================================
  Files         130      131       +1     
  Lines       27229    27399     +170     
==========================================
+ Hits        26437    26600     +163     
- Misses        792      799       +7     
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant